/*============================================================================*/
/*                                                                            */
/*  FILE       : PLATFORM.H                                                   */
/*  CONTENTS   : Typedefs and function prototypes that describe the platform  */
/*               being controlled.                                            */
/*----------------------------------------------------------------------------*/
/*    $Archive:: /Software/mbapi/release/include/dprio/PLATFORM.H            $*/
/*   $Revision:: 414                                                         $*/
/*----------------------------------------------------------------------------*/
/*  VISIBILITY : Public                                                       */
/*               Copyright (c) 1997 Motionbase PLC                            */
/*               All rights reserved.                                         */
/*----------------------------------------------------------------------------*/
/*  HISTORY    :                                                              */
/*                                                                            */
/*    Date     Author    Description                                          */
/*  08/12/97     KG      Made public.                                         */
/*  04/03/98     KG      mg.h removed                                         */
/*  10/03/98     KG      error codes moved to err_code.h                      */
/*  18/05/98     KG      getIO and setHostDataLatches added.                  */
/*                       Add exitMode and supporting enums.                   */
/*  22/05/98     KG      Add getMillisecondTick.                              */
/*  24/09/98     KG      Added:                                               */
/*                         getSoftStopInput                                   */
/*                         setSoftStopInput                                   */
/*                         getMotionRunningOutput                             */
/*                         setMotionRunningOutput                             */
/*  06/05/99     KG      Removed:                                             */
/*                         setHostDataLatch                                   */
/*                       Changed:                                             */
/*                         setHostDataLatches to include a millisecond time-  */
/*                         stamp.                                             */
/*                       Added:                                               */
/*                         'missedSampleThreshold' field to TMDU.             */
/*                         getMissedSampleThreshold                           */
/*                         setMissedSampleThreshold                           */
/*============================================================================*/
#ifndef _PLATFORM_H_
#define _PLATFORM_H_

#ifdef __cplusplus
extern "C" {
#endif

/*============================================================================*/
/* INCLUDES                                                                   */
/*============================================================================*/
#include "comp_def.h"                  /* Compiler switches, ...              */

/*============================================================================*/
/* MACROS                                                                     */
/*============================================================================*/
/*----------------------------------------------------------------------------*/
/* Return codes                                                               */
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
/* Interrupt code for the state machine handler.                              */
/* The state machine writes this value to the PC interrupt register in dual   */
/* port RAM every state machine period.                                       */
/*----------------------------------------------------------------------------*/
#define icSTATE_MACHINE_HANDLER 1
/*----------------------------------------------------------------------------*/
/* The maximum number of actuators that may be controlled by an MCC.          */
/*----------------------------------------------------------------------------*/
#define cnMAX_NUMBER_OF_ACTUATORS 6
#define cnNUMBER_OF_KINEMATICS_INPUTS 6
#define cnNUMBER_OF_KINEMATICS_OUTPUTS 6

/*============================================================================*/
/* ENUMERATIONS                                                               */
/*============================================================================*/
/*----------------------------------------------------------------------------*/
/* Enumerate categories of platform position.                                 */
/*----------------------------------------------------------------------------*/
typedef enum {
  pptNOT_HOMED,                        /* Absolute actuator positions unknown */
  pptUNKNOWN_POSITION,                 /* Between parked and neutral          */
  pptPARKED_POSITION,                  /* At parked position                  */
  pptNEUTRAL_POSITION,                 /* At neutral position                 */
  pptKNOWN_ARBITRARY_POSITION,         /* Whilst following                    */
  pptLAST                              /* For range checking                  */
} TPlatformPositionType;
/*----------------------------------------------------------------------------*/
/* Enumerate the state machine states.                                        */
/*----------------------------------------------------------------------------*/
typedef enum {
  smsUNKNOWN=-1,
  smsINITIAL=0,
  smsWAITING_FOR_LINK_OFF,
  smsPSU_DISABLED,
  smsWAITING_FOR_AMPLIFIER_TEMP_HEALTHY,
  smsWAITING_FOR_MOTOR_TEMP_HEALTHY,
  smsWAITING_FOR_INTERLOCKS_UNHEALTHY,
  smsWAITING_FOR_INTERLOCKS,
  smsWAITING_FOR_START,
  smsWAITING_FOR_END_OF_INRUSH,
  smsWAITING_FOR_LINK_IN_SPEC,
  smsWAITING_FOR_DUMP_FUSE_HEALTHY,
  smsWAITING_FOR_AMPLIFIERS_HEALTHY,
  smsHOMING,
  smsGOING_TO_NEUTRAL,
  smsIDLE,
  smsGOING_TO_PARKED,
  smsSTOPPING,
  smsFOLLOWING,
  smsINITIATING_EMERGENCY_STOP,
  smsEMERGENCY_STOPPING,
  smsUPS_REMOVING_DC_LINK,
  smsUPS_WAITING_FOR_LINK_OFF,
  smsUPS_WAITING_FOR_PLATFORM_STOPPED,
  smsUPS_WAITING_FOR_END_OF_INRUSH,
  smsUPS_WAITING_FOR_LINK_IN_SPEC,
  smsUPS_WAITING_FOR_DUMP_FUSE_HEALTHY,
  smsUPS_RECOVERY,
  smsUPS_WAITING_FOR_AMPLIFIER_HEALTHY,
  smsUPS_PARKING,
  smsLAST
} TStateMachineState;
/*----------------------------------------------------------------------------*/
/* Enumerate the platform commands.                                           */
/*----------------------------------------------------------------------------*/
typedef enum {
  pcNONE,                              /* Do nothing                          */
  pcENABLE_PSU,                        /* Start button may turn link on if    */
                                       /* interlocks healthy, etc.            */
  pcGO_TO_PARKED,                      /* Go to parked position               */
  pcGO_TO_NEUTRAL,                     /* Go to neutral position              */
  pcFOLLOW,                            /* Start to follow                     */
  pcSTOP,                              /* Go to parked position and power off */
  pcHOME,                              /* Home and return to neutral position */
  pcLAST                               /* For range checking                  */
} TPlatformCommand;
/*----------------------------------------------------------------------------*/
/* Define the available types of kinematics.                                  */
/* These types describe how the kinematics block generates its outputs from   */
/* the inputs.                                                                */
/*----------------------------------------------------------------------------*/
typedef enum {
  ktONE_TO_ONE,                        /* Output same as input                */
  ktSTEWART_PLATFORM,                  /* Stewart platform transformation     */
  kt3_DOF_TYPE_1,                      /* Custom 3 DOF transformation         */
  kt3_DOF_TYPE_2,                      /* Custom 3 DOF transformation         */
  ktLAST                               /* For range checking                  */
} TKinematicsType;
/*----------------------------------------------------------------------------*/
/* Enumerate PC calling codes used by DPR handler.                            */
/*----------------------------------------------------------------------------*/
typedef enum {
  _getActuator=0x8000,
  _getAnalogInput,
  _getDCLinkVoltage,
  _getDigitalInput,
  _getDigitalInputs,
  _getDigitalOutput,
  _getDigitalOutputs,
  _getExitMode,
  _getHostDataLatch,
  _getIO,
  _getKinematicsInputs,
  _getKinematicsOutputs,
  _getKinematicsType,
  _getMDU,
  _getMissedSampleThreshold,
  _getMillisecondTick,
  _getMotionRunningOutput,
  _getNeutralPosition,
  _getParkedPosition,
  _getPositionType,
  _getSoftStopInput,
  _getStateMachineState,
  _setActuator,
  _setDigitalOutput,
  _setDigitalOutputs,
  _setHostDataLatches,
  _setKinematicsType,
  _setMDU,
  _setMissedSampleThreshold,
  _setMotionRunningOutput,
  _setNeutralPosition,
  _setParkedPosition,
  _setPlatformCommand,
  _setSoftStopInput,
  _setStateMachinePeriod,
  _lastPlatformFunction
} publicFunctions;
/*----------------------------------------------------------------------------*/
/* Enumerate the possible reasons for parking.                                */
/*----------------------------------------------------------------------------*/
typedef enum {
  emHOST_REQUEST=0,                    /* Platform parked normally            */
  emINTERLOCK,                         /* Interlock chain broken              */
  emMOTOR_TEMP,                        /* Motor temperature fault             */
  emAMPLIFIER_TEMP,                    /* Amplifier temperature fault         */
  emHOST_WATCHDOG,                     /* Host watchdog fault                 */
  emUPS_RECOVERY,                      /* Low DC link voltage                 */
  emINRUSH_TIMEOUT,                    /* The inrush period did not end       */
  emBAD_DC_LINK,                       /* DC link out of spec on power up     */
  emBAD_DUMP_FUSE,                     /* The dump fuse unhealthy on power up */
  emNOT_HOMED,                         /* Homing failed                       */
  emLAST                               /* For range checking                  */
} TExitModes;
/*============================================================================*/
/* TYPEDEFS                                                                   */
/*============================================================================*/
/*----------------------------------------------------------------------------*/
/* Define a structure to hold 3-space coordinates.The array indices are as    */
/* follows:                                                                   */
/*   0 - x                                                                    */
/*   1 - y                                                                    */
/*   2 - z                                                                    */
/*----------------------------------------------------------------------------*/
typedef FLOAT TCoordinate[3];

/*----------------------------------------------------------------------------*/
/* Define a structure to hold data related to an actuator                     */
/*----------------------------------------------------------------------------*/
typedef struct {
  UINT axisNo;                         /* The number of the MCC axis          */
                                       /* assigned to this actuator.          */
  TCoordinate B;                       /* The coordinates of the base-end of  */
                                       /* the actuator in the base coordinate */
                                       /* frame.                              */
  TCoordinate pP;                      /* The coordinates of the platform-end */
                                       /* of the actuator in the platform     */
                                       /* coordinate frame.                   */
  INT sense;                           /* The direction in which the actuator */
                                       /* moves when encoder counts increase. */
                                       /* i.e.                                */
                                       /*  1: actuator extends for increasing */
                                       /*     counts,                         */
                                       /* -1: actuator retracts for increasing*/
                                       /*     counts.                         */
  FLOAT homeLength;                    /* The distance between universal      */
                                       /* joints when the actuator is in the  */
                                       /* home position.                      */
  FLOAT minExtension;                  /* The minimum allowed extension from  */
                                       /* the home position, i.e. (actuator   */
                                       /* length when actuator is as short as */
                                       /* possible) minus (actuator length    */
                                       /* when in home position).             */
  FLOAT maxExtension;                  /* The maximum allowed extension from  */
                                       /* the home position, i.e. (actuator   */
                                       /* length when actuator is as long as  */
                                       /* possible) minus (actuator length    */
                                       /* when in home position).             */
  FLOAT scale;                         /* Scale factor relating encoder counts*/
                                       /* to the units used for actuator      */
                                       /* lengths and coordinates.            */
  FLOAT kp;                            /* Servo proportional gain.            */
  FLOAT kvel;                          /* Servo velocity feedback gain.       */
  FLOAT kvelff;                        /* Servo velocity feedforward gain.    */
  FLOAT homingAccelRate;               /* Acceleration rate for homing        */
  FLOAT homingDecelRate;               /* Deceleration rate for homing        */
  FLOAT homingSlewSpeed;               /* Slew speed for homing               */
  FLOAT homingCurrentLimit;            /* Current limit (as a %) for homing   */
  INT homeSwitchInput;                 /* The number of the input used for the*/
                                       /* home switch.                        */
  INT enableOutput;                    /* The number of the output used for   */
                                       /* the enable signal.                  */
  INT   amplifierHealthyInput;         /* The channel used for healthy input  */
  FLOAT maximumSpeed;                  /* Maximum speed in mm/s               */
  FLOAT peakAcceleration;              /* Peak acceleration in mm/s/s         */
  FLOAT ratedAcceleration;             /* Rated acceleration in mm/s/s        */
} TActuator;
/*----------------------------------------------------------------------------*/
/* Define a structure to hold data related to an MDU.                         */
/*----------------------------------------------------------------------------*/
typedef struct
{
  UINT numberOfActuators;              /* The number of actuators             */
  /*--------------------------------------------------------------------------*/
  /* The input channel assigned to each of the functions.                     */
  /* These are automatically set when this structure is downloaded            */
  /* to the motion controller, so they do not need to be initialised by the   */
  /* user.                                                                    */
  /*--------------------------------------------------------------------------*/
  INT interlocksHealthyInput;
  INT startButtonPressedInput;
  INT linkIsOnInput;
  INT inrushFinishedInput;
  INT dumpingInput;
  INT dumpFuseHealthyInput;
  INT motorTempHealthyInput;
  INT amplifierTempHealthyInput;
  /*--------------------------------------------------------------------------*/
  /* The output channel assigned to each of the functions.                    */
  /* These are automatically set when this structure is downloaded            */
  /* to the motion controller, so they do not need to be initialised by the   */
  /* user.                                                                    */
  /*--------------------------------------------------------------------------*/
  INT bypassUPSInrushResistorOutput;
  INT inhibitDumpingOutput;
  INT enablePSUOutput;
  INT feedLinkFromUPSOutput;
  /*--------------------------------------------------------------------------*/
  /* Variables relating to the DC link voltage.                               */
  /*--------------------------------------------------------------------------*/
  FLOAT fullScaleLinkVoltage;          /* Link voltage when vLink reads 10v   */
  FLOAT noLoadLinkVoltageLowLimit;     /* The lower and upper link voltages   */
  FLOAT noLoadLinkVoltageHighLimit;    /* used for no-load health check.      */
  FLOAT onLoadLinkVoltageLowLimit;     /* The mains is deemed to have failed  */
                                       /* if the link falls below this value  */
                                       /* when on load.                       */
  INT vLinkInput;                      /* The analog input used for vLink     */
  FLOAT linkFilterTimeConstant;        /* The link measurement is filtered.   */
  UINT inrushPeriodTimeout;            /* The inrush period is expected to    */
                                       /* finish within this time.            */
  UINT noLoadLinkInSpecTimeout;        /* The link is expected to be in spec  */
                                       /* within this time.                   */
  UINT dumpFuseHealthyTimeout;         /* The dump fuse is expected to show   */
                                       /* healthy within this time.           */
  UINT UPSinrushTime;                  /* The inrush time when using the UPS. */
  UINT UPSextraInrushTime;             /* After the UPS inrush resistor is    */
                                       /* switched out of circuit, this much  */
                                       /* time is allowed before a load is    */
                                       /* applied.                            */
  UINT UPSnoLoadLinkInSpecTimeout;     /* The link is expected to be in spec  */
                                       /* within this time when using the UPS.*/
  UINT powerFailStationaryVelocity;    /* The velocity (in mru/s) below which */
                                       /* an actuator is deemed to be         */
                                       /* stationary after power has failed.  */
  /*--------------------------------------------------------------------------*/
  /* The state machine period in seconds.                                     */
  /*--------------------------------------------------------------------------*/
  FLOAT stateMachinePeriod;            /* Time between position updates       */
  /*--------------------------------------------------------------------------*/
  /* The number of samples for which the host may fail to provide new data    */
  /* when following before the platform is automatically returned to the      */
  /* Neutral position.                                                        */
  /*--------------------------------------------------------------------------*/
  ULONG missedSampleThreshold;
} TMDU;
/*----------------------------------------------------------------------------*/
/* Define a structure that combines the MDU with the actuators that it drives */
/*----------------------------------------------------------------------------*/
typedef struct {
  TMDU      mdu;
  TActuator actuator[cnMAX_NUMBER_OF_ACTUATORS];
} TPlatform;
/*----------------------------------------------------------------------------*/
/* Define types for the inputs and outputs of a kinematics block.             */
/*----------------------------------------------------------------------------*/
typedef FLOAT TKinematicsInputs[cnNUMBER_OF_KINEMATICS_INPUTS];
typedef FLOAT TKinematicsOutputs[cnNUMBER_OF_KINEMATICS_OUTPUTS];
/*============================================================================*/
/* GLOBAL DATA                                                                */
/*============================================================================*/
extern const CHAR* positionTypeDescriptor[pptLAST];

/*============================================================================*/
/* FUNCTION PROTOTYPES                                                        */
/*============================================================================*/
/*----------------------------------------------------------------------------*/
/* exitModeDescriptor                                                         */
/* Returns a string that describes why the platform was last parked.  The     */
/* string returned corresponds to the exit mode passed to the function.       */
/*                                                                            */
/* Args:                                                                      */
/* mode - the exit mode enum for which a string is required.                  */
/*                                                                            */
/* Return:                                                                    */
/* Address of character string or NULL if enum out of range.                  */
/*----------------------------------------------------------------------------*/
const CHAR FAR* exitModeDescriptor (TExitModes mode);

/*----------------------------------------------------------------------------*/
/* getActuator                                                                */
/* Passes all of the parameters for an actuator.  If the actuator number is   */
/* out of range an appropriate error code is returned, and no other action is */
/* taken.                                                                     */
/*                                                                            */
/* Args:                                                                      */
/* actuatorNo - the actuator index                                            */
/* pData      - where to store the data                                       */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/* erINVALID_ACTUATOR_INDEX                                                   */
/*----------------------------------------------------------------------------*/
CCONV INT getActuator (UINT actuatorNo, TActuator FAR* pData);

/*----------------------------------------------------------------------------*/
/* getAnalogInput                                                             */
/* Returns the value on ADC channel as raw data.                              */
/* There are eight 12-bit analog input channels each of which is configured   */
/* for single-ended +/-10v operation.                                         */
/* The inputs are converted on a round-robin basis 0,1,2,3,4,5,6,7,0,etc      */
/* within a 250us interrupt.  The interrupt reads the previous result then    */
/* starts a new conversion on the next channel.  If all eight channels are    */
/* being read new data will be available every 2ms.                           */
/*                                                                            */
/* Args:                                                                      */
/* channel - the ADC channel to be read.                                      */
/* pData   - where to store the data.                                         */
/*           -2048 <= value <= 2047  for bipolar aquisition                   */
/*           The high bits of the data read from the ADC are always masked    */
/*           off to provide 12 significant bits.                              */
/*                                                                            */
/* Return:                                                                    */
/* PASS - the function completed successfully.                                */
/* FAIL - erINVALID_CHANNEL                                                   */
/*----------------------------------------------------------------------------*/
CCONV INT getAnalogInput (BYTE channel, INT FAR* pData);

/*----------------------------------------------------------------------------*/
/* getDCLinkVoltage                                                           */
/* Retrieves the DC link voltage measured from the DIC.                       */
/*                                                                            */
/* Args:                                                                      */
/* pData - where to put the data (in volts).                                  */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS.                                                                 */
/*----------------------------------------------------------------------------*/
CCONV INT getDCLinkVoltage (FLOAT FAR* pData);

/*----------------------------------------------------------------------------*/
/* getDigitalInput                                                            */
/* Return the state of an individual user input channel.                      */
/*                                                                            */
/* Args:                                                                      */
/* channel - the input whose current state is required.                       */
/* pData   - where to store the result.                                       */
/*           0 - no current flows                                             */
/*           1 - current flows                                                */
/*                                                                            */
/* Return:                                                                    */
/* PASS - the function completed successfully.                                */
/* FAIL - erINVALID_INPUT                                                     */
/*----------------------------------------------------------------------------*/
CCONV INT getDigitalInput (BYTE channel, BYTE FAR* pData);

/*----------------------------------------------------------------------------*/
/* getDigitalInputs                                                           */
/* Returns the current state of all digital inputs.                           */
/*                                                                            */
/* Args:                                                                      */
/* pIn - a bitmap                                                             */
/*       0 - no current flows in the corresponding input circuit              */
/*       1 - current flows in the corresponding input circuit                 */
/*                                                                            */
/* Return:                                                                    */
/* PASS - the function completed successfully                                 */
/*----------------------------------------------------------------------------*/
CCONV INT getDigitalInputs (ULONG FAR* pIN);

/*----------------------------------------------------------------------------*/
/* getDigitalOutput                                                           */
/* Returns the current demanded state of a digital output.                    */
/*                                                                            */
/* Args:                                                                      */
/* channel - the output channel to be tested.                                 */
/* pData   - where to put the result.                                         */
/*           0 - no current flows in the output circuit                       */
/*           1 - current flows in the output circuit                          */
/*                                                                            */
/* Return:                                                                    */
/* PASS - the function completed successfully                                 */
/* FAIL - erINVALID_OUTPUT                                                    */
/*----------------------------------------------------------------------------*/
CCONV INT getDigitalOutput (BYTE channel, BYTE FAR* pData);

/*----------------------------------------------------------------------------*/
/* getDigitalOutputs                                                          */
/* Returns a bit map of the current output state.                             */
/*                                                                            */
/* Args:                                                                      */
/* pOut - where to store the data.                                            */
/*                                                                            */
/* Return:                                                                    */
/* PASS                                                                       */
/*----------------------------------------------------------------------------*/
CCONV INT getDigitalOutputs (ULONG FAR* pOut);

/*----------------------------------------------------------------------------*/
/* getExitMode                                                                */
/* Returns the reason why the platform last parked.  The reason is latched    */
/* until the interlock circuit next becomes healthy.                          */
/*                                                                            */
/* Args:                                                                      */
/* pMode - where to store the data.                                           */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT getExitMode (TExitModes FAR* pMode);

/*----------------------------------------------------------------------------*/
/* getHostDataLatch                                                           */
/* Retrieves a copy of the contents of one of the host data latches.          */
/*                                                                            */
/* Args:                                                                      */
/* latchNumber - the number of the data latch in question.                    */
/* pValue      - where to store the data                                      */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/* erDATA_LATCH_NUMBER_OUT_OF_RANGE                                           */
/*----------------------------------------------------------------------------*/
CCONV INT getHostDataLatch (UINT latchNo, FLOAT FAR* pValue);

/*----------------------------------------------------------------------------*/
/* getIO                                                                      */
/* Returns the state of digital and analog IO.                                */
/*                                                                            */
/* Args:                                                                      */
/* pDigitalInputs  - where to store bit map of inputs                         */
/* pDigitalOutputs - where to store bit map of outputs                        */
/* pAnalogInput0   - where to store analog input #0                           */
/* pAnalogInput1   - where to store analog input #1                           */
/* pAnalogInput2   - where to store analog input #2                           */
/* pAnalogInput3   - where to store analog input #3                           */
/* pAnalogInput4   - where to store analog input #4                           */
/* pAnalogInput5   - where to store analog input #5                           */
/* pAnalogInput6   - where to store analog input #6                           */
/* pAnalogInput7   - where to store analog input #7                           */
/*                                                                            */
/* Return:                                                                    */
/* PASS                                                                       */
/*----------------------------------------------------------------------------*/
/* Processing:                                                                */
/* Call MG function                                                           */
/*----------------------------------------------------------------------------*/
CCONV INT getIO (ULONG FAR* pDigitalInputs,
                 ULONG FAR* pDigitalOutputs,
                 INT FAR* pAnalogInput0,
                 INT FAR* pAnalogInput1,
                 INT FAR* pAnalogInput2,
                 INT FAR* pAnalogInput3,
                 INT FAR* pAnalogInput4,
                 INT FAR* pAnalogInput5,
                 INT FAR* pAnalogInput6,
                 INT FAR* pAnalogInput7);

/*----------------------------------------------------------------------------*/
/* getKinematicsInputs                                                        */
/* Get the current values of the inputs of the kinematics block.              */
/*                                                                            */
/* Args:                                                                      */
/* pData - where to store the input values                                    */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT getKinematicsInputs (TKinematicsInputs FAR pData);

/*----------------------------------------------------------------------------*/
/* getKinematicsOutputs                                                       */
/* Get the current values of the outputs of the kinematics block.             */
/*                                                                            */
/* Args:                                                                      */
/* pData - where to store the output values                                   */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT getKinematicsOutputs (TKinematicsOutputs FAR pData);

/*----------------------------------------------------------------------------*/
/* getKinematicsType                                                          */
/* Get the type of the currently installed kinematics block.                  */
/*                                                                            */
/* Args:                                                                      */
/* pData - where to put the kinematics type                                   */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT getKinematicsType (TKinematicsType FAR* pData);

/*----------------------------------------------------------------------------*/
/* getMDU                                                                     */
/* Returns the parameters that describe an MDU                                */
/*                                                                            */
/* Args:                                                                      */
/* pData - where to store the data                                            */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT getMDU (TMDU FAR* pData);

/*----------------------------------------------------------------------------*/
/* getMissedSampleThreshold                                                   */
/* Returns the number of consecutive samples for which the host PC may fail   */
/* to supply new data, whilst smsFOLLOWING. When the number of missed samples */
/* is equal to this threshold value the platform is automatically returned to */
/* the Neutral position. A Missed Sample counter is incremented each time the */
/* host PC fails to supply new data and is decremented if new data is made    */
/* available.  This counter is not decremented below zero.                    */
/*                                                                            */
/* Args:                                                                      */
/* pThreshold - where to store the data                                       */
/*              If the threshold is set to zero, checking is turned off.      */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT getMissedSampleThreshold (ULONG* pThreshold);

/*----------------------------------------------------------------------------*/
/* getMillisecondTick                                                         */
/* Returns the current value of the free running counter incremented every    */
/* millisecond.                                                               */
/*                                                                            */
/* Args:                                                                      */
/* pTick - where to store the data                                            */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT getMillisecondTick (LONG FAR* pTick);

/*----------------------------------------------------------------------------*/
/* getMotionRunningOutput                                                     */
/* Returns the digital output that is used to indicate that the state machine */
/* is in state smsFOLLOWING.  A value of -1 indicates that no output is used. */
/*                                                                            */
/* Args:                                                                      */
/* pData   - where to store the data.                                         */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT getMotionRunningOutput (INT FAR* pData);

/*----------------------------------------------------------------------------*/
/* getNeutralPosition                                                         */
/* Allows the neutral position of a platform to be interrogated               */
/*                                                                            */
/* Args:                                                                      */
/* pData - where to store the data                                            */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT getNeutralPosition (TKinematicsInputs FAR pData);

/*----------------------------------------------------------------------------*/
/* getParkedPosition                                                          */
/* Allows the parked position of a platform to be interrogated                */
/*                                                                            */
/* Args:                                                                      */
/* pData - where to store the data                                            */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT getParkedPosition (TKinematicsInputs FAR pData);

/*----------------------------------------------------------------------------*/
/* getPositionType                                                            */
/* Get the type of the current position.                                      */
/*                                                                            */
/* Args:                                                                      */
/* pData - where to store the description of the position                     */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT getPositionType (TPlatformPositionType FAR* pData);

/*----------------------------------------------------------------------------*/
/* getSoftStopInput                                                           */
/* Returns the digital input that is used to command the platform to return   */
/* to its parked position.  A value of -1 indicates that no input is used.    */
/*                                                                            */
/* Args:                                                                      */
/* pData   - where to store the data.                                         */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT getSoftStopInput (INT FAR* pData);

/*----------------------------------------------------------------------------*/
/* getStateMachineState                                                       */
/* Get the state machine state.                                               */
/*                                                                            */
/* Args:                                                                      */
/* pData - where to store the state machine state                             */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT getStateMachineState (TStateMachineState FAR* pData);

/*----------------------------------------------------------------------------*/
/* setActuator                                                                */
/* Sets all of the parameters for an actuator.  If the actuator index is out  */
/* of range an appropriate error code is returned, and no other action is     */
/* taken.  It is only the 'constant' parameters that are set, the length      */
/* element of the TActuator structure is ignored.                             */
/*                                                                            */
/* Args:                                                                      */
/* index - the actuator index                                                 */
/* pData - where to find the actuator data                                    */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/* erINVALID_ACTUATOR_INDEX                                                   */
/* FAIL                                                                       */
/*----------------------------------------------------------------------------*/
CCONV INT setActuator (UINT index, TActuator FAR* pData);

/*----------------------------------------------------------------------------*/
/* setDigitalOutput                                                           */
/* Sets an individual digital output.                                         */
/*                                                                            */
/* Args:                                                                      */
/* channel - the output channel to be controlled.                             */
/* state   - the desired state - 0: no current flows in the output circuit    */
/*                               1: current flows in the output circuit       */
/*                                                                            */
/* Return:                                                                    */
/* PASS - the function completed successfully - the output was written.       */
/* FAIL - erINVALID_OUTPUT                                                    */
/*      - erVALUE_OUT_OF_RANGE                                                */
/*----------------------------------------------------------------------------*/
CCONV INT setDigitalOutput (BYTE channel, BYTE state);

/*----------------------------------------------------------------------------*/
/* setDigitalOutputs                                                          */
/* Set the digital outputs as a block.                                        */
/*                                                                            */
/* Args:                                                                      */
/* bitMappedOutputs - 0 : if no current should flow in the output circuit     */
/*                    1 : if current should flow in the output circuit        */
/*                                                                            */
/* Return:                                                                    */
/* PASS - the function completed successfully                                 */
/* FAIL - erVALUE_OUT_OF_RANGE                                                */
/*----------------------------------------------------------------------------*/
CCONV INT setDigitalOutputs (ULONG bitMappedOutputs);

/*----------------------------------------------------------------------------*/
/* setHostDataLatches                                                         */
/* Loads all of the data latches with data. This is intended to be used by    */
/* host to provide regular updates to the filter inputs. A time stamp that    */
/* indicates the time at which the data was valid may be supplied.            */
/*                                                                            */
/* Args:                                                                      */
/* latch0    - data for latch #0                                              */
/* latch1    - data for latch #1                                              */
/* latch2    - data for latch #2                                              */
/* latch3    - data for latch #3                                              */
/* latch4    - data for latch #4                                              */
/* latch5    - data for latch #5                                              */
/* timeStamp - time at which the data was valid in milliseconds.              */
/*             Set to -1 to use MCC clock to time stamp.                      */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/* erVALUE_OUT_OF_RANGE                                                       */
/*----------------------------------------------------------------------------*/
CCONV INT setHostDataLatches (FLOAT latch0,
                              FLOAT latch1,
                              FLOAT latch2,
                              FLOAT latch3,
                              FLOAT latch4,
                              FLOAT latch5,
                              LONG timeStamp);

/*----------------------------------------------------------------------------*/
/* setKinematicsType                                                          */
/* Install one of the available kinematics blocks.                            */
/*                                                                            */
/* Args:                                                                      */
/* type - the type of kinematics block to be installed                        */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/* erBAD_KINEMATICS_TYPE                                                      */
/*----------------------------------------------------------------------------*/
CCONV INT setKinematicsType (TKinematicsType type);

/*----------------------------------------------------------------------------*/
/* setMDU                                                                     */
/* Loads a set of parameters that describe an MDU                             */
/*                                                                            */
/* Args:                                                                      */
/* pData - where to find the data                                             */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT setMDU (TMDU FAR* pData);

/*----------------------------------------------------------------------------*/
/* setMissedSampleThreshold                                                   */
/* Sets the number of consecutive samples for which the host PC may fail      */
/* to supply new data, whilst smsFOLLOWING. When the number of missed samples */
/* is equal to this threshold value the platform is automatically returned to */
/* the Neutral position. A Missed Sample counter is incremented each time the */
/* host PC fails to supply new data and is decremented if new data is made    */
/* available.  This counter is not decremented below zero.                    */
/*                                                                            */
/* Args:                                                                      */
/* threshold - new threshold value.                                           */
/*             If the threshold is set to zero, checking is turned off.       */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT setMissedSampleThreshold (ULONG threshold);

/*----------------------------------------------------------------------------*/
/* setMotionRunningOutput                                                     */
/* Selects the digital output that is used to indicate that the state machine */
/* is in state smsFOLLOWING.  A value of -1 indicates that no output is used. */
/*                                                                            */
/* Args:                                                                      */
/* outputNo - the digital output channel to use.                              */
/*                                                                            */
/* Return:                                                                    */
/* PASS                                                                       */
/* FAIL - erINVALID_OUTPUT                                                    */
/*----------------------------------------------------------------------------*/
CCONV INT setMotionRunningOutput (INT outputNo);

/*----------------------------------------------------------------------------*/
/* setNeutralPosition                                                         */
/* Allows the neutral position of a platform to be specified.                 */
/*                                                                            */
/* Args:                                                                      */
/* pData - where to find the data                                             */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT setNeutralPosition (TKinematicsInputs FAR pData);

/*----------------------------------------------------------------------------*/
/* setParkedPosition                                                          */
/* Allows the parked position of a platform to be specified.                  */
/*                                                                            */
/* Args:                                                                      */
/* pData - where to find the data                                             */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT setParkedPosition (TKinematicsInputs FAR pData);

/*----------------------------------------------------------------------------*/
/* setPlatformCommand                                                         */
/* Writes a platform command (pcXXX value) to the state machine.              */
/*                                                                            */
/* Args:                                                                      */
/* command - the platform command to write                                    */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT setPlatformCommand (TPlatformCommand command);

/*----------------------------------------------------------------------------*/
/* setSoftStopInput                                                           */
/* Assigns the digital input that is used to command the platform to return   */
/* to its parked position.  A value of -1 indicates that no input is used.    */
/*                                                                            */
/* Args:                                                                      */
/* inputNo - the input that should be used.                                   */
/*                                                                            */
/* Return:                                                                    */
/* PASS                                                                       */
/* FAIL - erINVALID_INPUT                                                     */
/*----------------------------------------------------------------------------*/
CCONV INT setSoftStopInput (INT inputNo);

/*----------------------------------------------------------------------------*/
/* setStateMachinePeriod                                                      */
/* Sets the rate at which the state machine on the MCC will run.              */
/*                                                                            */
/* Args:                                                                      */
/* period - the state machine period in seconds. (>=0.002)                    */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/* erVALUE_OUT_OF_RANGE                                                       */
/*----------------------------------------------------------------------------*/
CCONV INT setStateMachinePeriod (FLOAT period);

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* _PLATFORM_H_ */
/*============================================================================*/
/* END OF FILE                                                                */
/*============================================================================*/
